package com.blog.cmrpersonalblog.service;

import com.blog.cmrpersonalblog.dto.auth.request.SendVerificationCodeRequest;
import com.blog.cmrpersonalblog.dto.auth.request.VerifyEmailCodeRequest;
import com.blog.cmrpersonalblog.dto.auth.response.EmailVerificationResponse;

/**
 * 邮箱验证服务接口
 */
public interface EmailVerificationService {

    /**
     * 发送验证码
     * @param request 发送请求
     * @param ipAddress IP地址
     * @param userAgent 用户代理
     * @return 发送结果
     */
    EmailVerificationResponse sendVerificationCode(SendVerificationCodeRequest request, 
                                                  String ipAddress, String userAgent);

    /**
     * 验证验证码
     * @param request 验证请求
     * @return 验证结果
     */
    boolean verifyCode(VerifyEmailCodeRequest request);

    /**
     * 验证验证码并标记为已使用
     * @param request 验证请求
     * @return 验证结果
     */
    boolean verifyAndUseCode(VerifyEmailCodeRequest request);

    /**
     * 检查验证码是否有效
     * @param email 邮箱
     * @param verificationCode 验证码
     * @param verificationType 验证类型
     * @return 是否有效
     */
    boolean isCodeValid(String email, String verificationCode, String verificationType);

    /**
     * 使指定邮箱的验证码失效
     * @param email 邮箱
     * @param verificationType 验证类型
     * @return 是否成功
     */
    boolean invalidateVerifications(String email, String verificationType);

    /**
     * 清理过期验证码
     * @return 清理数量
     */
    Integer cleanExpiredVerifications();

    /**
     * 检查发送频率限制
     * @param email 邮箱
     * @param verificationType 验证类型
     * @return 是否可以发送
     */
    boolean canSendVerification(String email, String verificationType);

    /**
     * 获取剩余发送次数
     * @param email 邮箱
     * @return 剩余次数
     */
    Integer getRemainingDailyCount(String email);

    /**
     * 生成验证码
     * @return 6位数字验证码
     */
    String generateVerificationCode();
}
